package org.xml.sax;


/**
 * SAX错误处理程序的基本接口
 *
 * 如果SAX应用程序需要实现自定义错误处理，则必须实现此接口，然后使用{@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler}方法设置。
 *
 * 解析器会通过这个接口报告所有的错误和警告.
 *
 * 注意：如果应用程序没有注册错误处理程序，那么XML解析错误将不会被报告，除了 SAXParse Exception将被抛出致命的错误。
 *
 * 为了检测有效性错误，必须注册一个用{@link #error error()} 调用做某事的错误处理程序。
 *
 *
 * 对于XML处理错误，SAX驱动程序必须优先使用此接口来引发异常：由应用程序决定是否针对不同类型的错误和警告引发异常。
 *
 * 但请注意，在调用{@link #fatalError fatalError}后，解析器不会继续报告其他错误。
 * 换句话说，在报告任何致命错误之后，SAX驱动程序类可能会抛出异常.
 * 解析器也可能会为非XML错误引发适当的异常。
 * 例如， {@link XMLReader#parse XMLReader.parse()} 将在访问实体或文档时发生IOException异常。
 *
 * @version 2.0.1+ (sax2r3pre1)
 * @see org.xml.sax.XMLReader#setErrorHandler
 * @see org.xml.sax.SAXParseException
 */
public interface ErrorHandler {


    /**
     * 接收到警告的通知。
     *SAX解析器将使用此方法来报告XML建议中定义的非错误或致命错误的条件。 默认行为是不采取行动。
     *SAX解析器必须在调用此方法后继续提供正常的解析事件：应用程序仍然可以处理文档。
     *过滤器也可以使用此方法报告其他非XML警告。
     * @param exception 警告信息封装在SAX解析异常中
     * @exception org.xml.sax.SAXException Any SAX exception, possibly wrapping another exception.
     * @see org.xml.sax.SAXParseException
     */
    public abstract void warning (SAXParseException exception)
    throws SAXException;


    /**
     * 接收可恢复错误的通知。
     *
     * 这对应于W3C XML 1.0建议书第1.2节中“错误”的定义。 例如，验证解析器将使用此回调来报告违反有效性约束的情况。 默认行为是不采取行动。
     *
     * SAX解析器必须在调用此方法后继续提供正常的解析事件：应用程序仍然可以处理文档
     * 如果应用程序不能这样做，那么解析器应该报告一个致命错误，即使XML建议不要求这样做。
     *
     * 过滤器也可以使用此方法报告其他非XML错误。
     *
     * @param exception 错误信息封装在SAX解析异常中。
     * @exception org.xml.sax.SAXException Any SAX exception, possibly wrapping another exception.
     * @see org.xml.sax.SAXParseException
     */
    public abstract void error (SAXParseException exception)
    throws SAXException;


    /**
     * 接收不可恢复错误的通知。
     *
     * 此方法的文档与{@link org.xml.sax.ContentHandler#endDocument}文档之间存在明显的矛盾,
     *在未来的主要版本中解决这个歧义之前，客户端应该不会假设当分析器报告了一个致命的Error（）或抛出异常时，Document（）是否将被调用。
     *
     *
     * 这对应于W3C XML 1.0 Recommendation第1.2节中“致命错误”的定义。 例如，解析器将使用此回调来报告违反格式良好的约束。
     *应用程序必须假定文档在解析器调用此方法后不可用，并且应该继续（如果有的话）仅为了收集其他错误消息：
     * 事实上，SAX解析器可以自由地停止报告任何其他事件 方法已被调用。
     *
     * @param exception 错误信息封装在SAX解析异常中。
     * @exception org.xml.sax.SAXException Any SAX exception, possibly wrapping another exception.
     * @see org.xml.sax.SAXParseException
     */
    public abstract void fatalError (SAXParseException exception)
    throws SAXException;

}
